Repository Management with Nexus

The following changes were made in 3.0.1:

The following changes were made in 3.0:

The following people helped improve the quality of Edition 3.0 by reporting typos, making suggestions, or contributing directly to the development of this book:

Nexus manages software “artifacts” required for development, deployment, and provisioning. If you develop software, Nexus can help you share those artifacts with other developers and end-users. Maven’s central repository has always served as a great convenience for users of Maven, but it has always been recommended to maintain your own repositories to ensure stability within your organization. Nexus greatly simplifies the maintenance of your own internal repositories and access to external repositories. With Nexus you can completely control access to, and deployment of, every artifact in your organization from a single location.

Nexus Open Source provides you with an essential level of control over the external Maven repositories you use and the internal repositories you create. It provides infrastructure and services for organizations that use repository managers to obtain and deliver software. If you create software libraries or applications for your end-users, you can use Nexus Open Source to distribute your software. If your software depends upon open source software components, you can cache software artifacts from remote repositories.

Nexus Professional was designed to meet the needs of the enterprise. It is a central point of access to external repositories which provides the necessary controls to make sure that only approved artifacts enter into your software development environment. It is also a central distribution point with the intelligence required to support the decision that go into making quality software. The extensibility provided by the custom metadata plugin coupled with REST services only available in Nexus Professional also lay the foundation for highly complex interactions within the enterprise. Once you start to use the workflow and decision support features of Nexus Professional, you will start to see it as the “assembly line” - the central collaboration point for your software development efforts.

If you are wondering which edition is appropriate for your organization. The following sections outline some reasons for choosing either Nexus Open Source of Nexus Professional.

Proximity in December 2005 as he was trying to find a way to isolate his own systems from an incredibly slow ADSL connection provided by a Hungarian ISP. Proximity started as a simple web application to proxy artifacts for a small organization with connectivity issues. Creating a local on-demand cache for Maven artifacts from the Maven Central repository gave an organization access to the artifacts on the Maven Central Repository, but it also made sure that these artifacts weren’t downloaded over a very slow ADSL connection used by a number of developers. In 2007,

Sonatype asked Tamas to help create a similar product named Nexus. Nexus is currently considered the logical next step to Proximity. Nexus currently has an active development team, and portions of the indexing code from Nexus are also being used in m2eclipse.

Repository managers serve two purposes: they act as highly configurable proxies between your organization and the public Maven repositories and they also provide an organization with a deployment destination for its own generated artifacts. Just as Source Code Management (SCM) tools are designed to manage source artifacts, Repository Managers have been designed to manage and track external dependencies and artifacts generated by your build. They are an essential part of any enterprise or open-source software development effort, and they enable greater collaboration between developers and wider distribution of software.

Maven developers are familiar with the concept of a repository: a collection of binary software artifacts and metadata stored in a defined directory structure which is used by clients such as Apache Ivy to retrieve binaries during a build process. In the case of the Maven repository, the primary type of binary artifact is a JAR file containing Java bytecode, but there is no limit to what type of artifact can be stored in a Maven repository. For example, one could just as easily deploy documentation archives, source archives, Flash libraries and applications, or Ruby libraries to a Maven repository. A Maven repository provides a platform for the storage, retrieval, and management of binary software artifacts and metadata.

In Maven, every software artifact is described by an XML document called a Project Object Model (POM). This POM contains information that describes a project and lists a project’s dependencies - the binary software artifacts which a given component depends upon for successful compilation or execution.

When Maven downloads a dependency from a repository, it also downloads that dependency’s POM. Given a dependency’s POM, Maven can then download any other libraries which are required by that dependency. The ability to automatically calculate a project’s dependencies and transitive dependencies is made possible by the standard and structure set by the Maven repository.

Maven and other tools such as Ivy which interact with a repository to search for binary software artifacts, model the projects they manage, and retrieve software artifacts on-demand from a repository. When you download and install Maven without any customization, Maven will retrieve artifacts from a Maven Central repository which serves millions of Maven users every single day. While you can configure Maven to retrieve binary software artifacts from a collection of mirrors, the best-practice is to install Nexus and use it to proxy and cache the contents of Central on your own network. <indexterm>

In addition to Central, there are a number of major organizations such as Redhat, Sun Microsystems, and Codehaus which maintain separate repositories.

While this might seem like a simple, obvious mechanism for distributing artifacts, the Java platform existed for several years before the Maven project created a formal attempt at the first repository for Java artifacts. Until the advent of the Maven repository in 2002, a project’s dependencies were gathered in a manual, ad-hoc process and were often distributed with a project’s source code. As applications grew more and more complex, and as software teams developed a need for more complex dependency management capabilities for larger enterprise applications, Maven’s ability to automatically retrieve dependencies and model dependencies between components became an essential part of software development.

If you use Maven, you are using a repository to retrieve artifacts and Maven plugins. In fact, Maven used a Maven repository to retrieve core plugins that implement the bulk of the features used in your builds. Once you start to rely on repositories, you realize how easy it is to add a dependency on an open source software library available in the Maven Central repository, and you might start to wonder how you can provide a similar level of convenience for your own developers. When you install a repository manager, you are bringing the power of a repository like Central into your organization, you can use it to proxy Central, and host your own repositories for internal and external use. In this section, we discuss the core functionality which defines what a repository manager does.

Put simply, a repository manager provides two core features:

In addition to these two core features, a repository manager also allows you to manage binary software artifacts through the software development lifecycle, search and catalog software artifacts, audit development and release transactions, and integrate with external security systems such as LDAP. The following sections define the feature sets of Nexus Open Source and Nexus Professional.

Here are a few reasons why using a repository manager is an imperative. While most people wouldn’t even think of developing software without the use of a source code control system like Subversion or Perforce, the concept of using a repository manager is still something that needs development. There are many who use Maven for years without realizing the benefits of using a repository manager. This section was written as an attempt to capture some of the benefits of using a repository manager.

This section talks about the stages of moving to a repository manager. Adopting a repository manager is not an all or nothing proposition, and there are various levels (or stages) of adoption that can be distinguished when approaching repository management. On one end of the adoption spectrum is the organization that installs a repository manager just to control and consolidate access to a set of remote repositories. On the other end of the spectrum is the organization which has integrated the repository manager into an efficient software development lifecycle, using it to facilitate decision points in the lifecycle, encouraging more efficient collaboration throughout the enterprise, and keeping detailed records to increase visibility into the software development process.

There are two distributions of Nexus: Nexus Open Source and Nexus Professional. Nexus Open Source is a fully-featured repository manager which can be freely used, customized, and distributed under the GNU Affero General Public License (AGPL) Version 3. Nexus Professional is a distribution of Nexus with features that are relevant to large enterprises and organizations which require complex procurement and staging workflows in addition to more advanced LDAP integration, Atlassian Crowd support, and other development infrastructure. The differences between Nexus Open Source and Nexus Professional are explored in the previous chapter.

The following sections detail the installation process for both Nexus Open Source and Nexus Professional.

Since Nexus separates its configuration and data storage from the application, it is easy to upgrade an existing Nexus installation. To upgrade Nexus, unpack the Nexus archive in the directory which contains the existing Nexus installation. Once the archive is unpacked, the new Nexus application directory should be a sibling to your existing sonatype-work/ directory. If you have defined a symbolic link for the version of Nexus to use, change that to point at the new Nexus application directory. When you start the new instance of Nexus it will read the existing repository configuration from the sonatype-work/

When you start Nexus, you are starting a web server on the default port of 0.0.0.0:8081. Nexus runs within a servlet container called Jetty and it is started with a native service wrapper called the Tanuki Java Service Wrapper. This service wrapper can be configured to run Nexus as a Windows service or a Unix daemon. To start Nexus, you will need to find the appropriate startup script for your platform. To see the list of available platforms, list the contents of the

The following example listing starts Nexus using the script for Mac you the available platforms, then we make the contents of the bin directory executable with chmod. The Mac OS X wrapper is started with a call to nexus start, and then we tail the wrapper.log in stating what IP address and port it is listening on.

At this point, Nexus will be running and listening on all IP addresses (0.0.0.0) that are configured for the current host on port 8081. To use Nexus, fire up a web browser and type in the URL: http://localhost:8081/nexus

While we use "localhost" throughout this book, you may need to use the IP Loopback Address of "127.0.0.1" or the IP address assigned to the machine running Nexus. Click on the "Log In" link in the upper right-hand corner of the web page, and you should see the login dialog. THE DEFAULT NEXUS USERNAME AND PASSWORD IS "admin" AND "admin123".

Nexus ships with some default passwords and settings for repository indexing that need to be changed for your installation to be useful (and secure). After installing and running Nexus, you need to make sure that you complete the following tasks:

This will trigger Nexus to re-index these repositories, during which the remote index files will be downloaded. It might take Nexus a few minutes to download the entire index, but once you have it, you’ll be able to search the entire contents of the Maven repository.

Once you’ve enabled remote index downloads, you still won’t be able to browse the complete contents of a remote repository. Downloading the remote index allows you to search for artifacts in a repository, but until you download those artifacts from the remote repository they will not show in the repository tree when you are browsing a repository. When browsing a repository, you will only be shown artifacts which have been downloaded from the remote repository.

When installing Nexus, you will often want to configure Nexus as a service. If you are on Windows, the Nexus distribution includes binaries that can work with the Windows Services subsystem and if you are on another platform such as GNU/Linux Nexus also includes scripts that can be configured to start Nexus as a service. The following sections provide instructions for configuring Nexus as a service.

If you installed Nexus as a stand-alone application, Nexus is running on a high-performance servlet container based on Java NIO. From a performance perspective, there is no reason for you not to run Nexus by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate multiple disparate applications using tools like mod_rewrite. For this reason, we’ve included some brief instructions for configuration Apache httpd. We assume that you’ve already installed Apache 2, and that you are using a Virtual Host for www.somecompany.com.

Let’s assume that you wanted to host Nexus behind Apache HTTPd at the URL http://www.somecompany.com. To do this, you’ll need to change the context path that Nexus is served from.

At this point, edit the HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Nexus via mod_proxy at http://www.somecompany.com/

If you just wanted to continue to serve Nexus at the /nexus context path, you would not change the contextPath in in your ProxyPass and ProxyPassReverse

Apache configuration is going to vary based on your own application’s requirements and the way you intend to expose Nexus to the outside world. If you need more details about Apache httpd and mod_proxy, please see http://httpd.apache.org

The Nexus Open Source WAR has been successfully tested in Tomcat, Jetty, and Resin. If you need to run Nexus under Glassfish, please see <xref linkend="install-sect-war-gf" />. To download the Nexus Open Source WAR, go to http://nexus.sonatype.org/using/download.html. Click on the Download Site link and then download the Nexus WAR. Once you have downloaded the Nexus Open Source WAR, you can install it in a servlet container or application server.

The process for installing a WAR in an servlet container or application server is going to vary for each specific application. Often, this installation process is as simple as dropping a WAR file in a special directory and restarting the container. For example, to install the Nexus WAR in Tomcat, drop the your Tomcat instance. Assuming that Tomcat is configured on port 8080 once Tomcat is started, Nexus will be available on http://localhost:8080/nexus-webapp-1.6.0.

If you would like a less verbose URL, copy nexus-webapp-1.6.0.war to a file named nexus.war before copying the distribution to

To install a Nexus Professional license, click on Licensing in the Enterprise menu. Clicking on Licensing will bring up the panel shown in <xref linkend="fig-installations-licensing" />. To upload your Nexus Professional license, click on Browse…, select the file, and click on Upload.

Once you have selected a license and uploaded it to Nexus, Nexus Professional will display a dialog box with the Nexus Professional End-user License Agreement as shown in <xref linkend="fig-installation-eula" />. If you agree with the terms and conditions, click on "I Agree".

Once you have agreed to the terms and conditions contained in the End User License Agreement, Nexus Professional will then display a dialog box confirming the installation of a Nexus Professional license as shown in <xref linkend="fig-installation-license-upload-config" />.

If you need to move your Nexus Professional license, you can click on the "Uninstall License" button at the bottom of the Licensing Panel. Clicking on this button will show the dialog in <xref linkend="fig-installation-config-uninstall" /> which confirms that you want to uninstall a license.

Clicking Yes in this dialog box will uninstall the license from Nexus Professional and display another dialog which confirms that the license has been successfully uninstalled.

The following sections describe the various directories that are a part of any Nexus installation. When you install Nexus Open Source or Nexus Professional, you are creating two directories: a directory which contains the Nexus runtime and application, and a directory which contains your own configuration and data. When you upgrade to a newer version of Nexus, you replace the Nexus application directory and retain all of your own custom configuration and repository data in sonatype-work/

To use Nexus, you will configure Maven to check Nexus instead of the public repositories. To do this, you’ll need to edit your mirror settings in your <filename>~/.m2/settings.xml file. First, we’re going to demonstrate how to configure Maven to consult your Nexus installation instead of retrieving artifacts directly from the Maven Central repository. After we override the central repository and demonstrate that Nexus is working, we’ll circle back to provide a more sensible set of settings that will cover both releases and snapshots.

If you are adopting Nexus for internal development you should configure a single Nexus group which contains both releases and snapshots. To do this, add snapshot repositories to your public group, and add the following mirror configuration to your Maven settings in ~/.m2/settings.xml

In <xref linkend="ex-maven-nexus-simple" /> we have defined a single profile: nexus profile is configured to download from the central repository with a bogus URL. This URL is overridden by the mirror setting in the same settings.xml file to point to the URL of your single Nexus group. The nexus group is then listed as an active profile in the <sgmltag>activeProfiles element.

If you’ve configured your Maven settings.xml to list the Nexus public group as a mirror for all repositories, you might encounter projects which are unable to retrieve artifacts from your local Nexus installation. This usually happens because you are trying to build a project which has defined a custom set of repositories and snapshotRepositories in a pom.xml. When you encounter a project which contains a custom repository element in a pom.xml add this repository to Nexus as a new proxy repository and then add the new proxy repository to the public group.

To add a repository, log into Nexus as an Administrator, and click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Clicking on this link should bring up a window that lists all of the repositories which Nexus knows about. You’ll then want to create a new proxy repository. To do this, click on the Add link that is directly above the list of repositories. When you click the Add button, click the down arrow directly to the right of the word Add, this will show a drop-down which has the options: Hosted Repository, Proxy Repository, Virtual Repository, and Repository Group. Since you are creating a proxy repository, click on Proxy Repository.

Once you do this, you will see a screen resembling <xref linkend="fig-add-repo" />. Populate the required fields Repository ID and the Repository Name with "caja" and "Google Caja". Set the Repository Policy to "Release", and the Remote Storage Location to http://google-caja.googlecode.com/svn/maven

Once you’ve filled out this screen, click on the Save button. Nexus will then be configured with the caja proxy repository. Do the same thing for the oauth repository. Create a repository with the Repository ID of oauth, with a Release policy, and the Remote Storage Location of http://oauth.googlecode.com/svn/code/maven

Next you will need to add both of these new repositories to the public Nexus Group. To do this, click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Nexus lists Groups and Repositories in the same list so click on the public group. After clicking on the public group, you should see the Browse and Configuration tabs in the lower half of the Nexus window.

Clicking on the Configuration tab will bring up a screen which looks like <xref linkend="fig-add-to-group" />.

To add the two new repositories to the public Nexus Group, find the repositories in the Available Repositories list on the right, click on the repository you want to add and drag it to the left to the Ordered Group Repositories list. Once the repository is in the Ordered Group Repositories list you can click and drag the repository within that list to alter the order in which a repository will be searched for a matching artifact. Once the Google Caja and Google OAuth project repositories are added to the public Nexus Group, you should be able to build Apache Shindig and watch Maven download the Caja and OAuth artifacts from the respective repositories.

In the last few sections, you encountered a situation where you needed to add two custom repositories to a build in order to download two libraries (Google Caja and Google OAuth) which are not available in the Maven Central repository. If you were not using a repository manager, you would have added these repositories to the repository element of your project’s POM, or you would have asked all of your developers to modify ~/.m2/settings.xml to reference two new repositories. Instead, you used the Nexus repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group in Nexus, you can freely swap in new repositories without asking your developers to change local configuration, and you’ve gained a certain amount of control over which repositories are made available to your development team.

Nexus provides for anonymous access for users who only need to search repositories, browse repositories, and peruse the system feeds. This anonymous access level changes the navigation menu and some of the options available when you right-click on a repository. This read-only access displays a user interface shown in <xref linkend="fig-repoman-anonymous-interface" />.

One of the most straightforward uses of the Nexus is to browse the structure of a Maven repository. If you click on the Browse Repositories menu item in the Views menu, you should see the following display. The top-half of <xref linkend="fig-nexus-browse-repo" /> shows you a list of groups and repositories along with the type of the repository and the repository status. To browse the artifacts that are stored in a local Nexus instance, click on the Browse Storage tab for a repository as shown in <xref linkend="fig-nexus-browse-repo" />.

When you are browsing a repository, you can right click on any file and download it directly to your browser. This allows you to retrieve specific artifacts manually, or examine a <acronym>POM file in the browser.

A Nexus proxy repository acts as a local cache for a remote repository, in addition to downloading and caching artifacts locally, Nexus will also download an index of all the artifacts stored in a particular repository. When searching or browsing for artifacts, it is often more useful to search and browse the repository index. To view the repository index, click on the Browse Index tab for a particular repository to load the interface shown in <xref linkend="fig-nexus-browse-repo-index" />.

As shown in <xref linkend="fig-nexus-browse-repo-index" />, if an artifact has been downloaded from a remote repository and cached in Nexus, the artifact or folder will display a small Nexus logo.

Nexus contains ordered groups of repositories which allow you to expose a series of repositories through a single URL. More often than not, an organization is going to point Maven at the two default Nexus groups: Public Repositories and Public Snapshot Repositories. Most end-users of Nexus are not going to know what artifacts are being served from what specific repository, and they are going to want to be able to browse the Public Repository. To support this use case, Maven allows you to browse the contents of a Nexus Group as if it were a single merged repository with a tree structure. <xref linkend="fig-nexus-browse-group" />, shows the browsing storage interface for a Nexus Group. There is no difference to the user experience of browsing a Nexus Group vs. browsing a Nexus Repository.

When browsing a Nexus group’s storage, you are browsing the underlying storage for all of the repositories which are contained in a group. If a Nexus group contains proxy repositories, the Browse Storage tab will show all of the artifacts in the Nexus group that have been download from the remote repositories. To browse and search all artifacts available in a Nexus group, click on the Browse Index tab to load the interface shown in <xref linkend="fig-nexus-browse-group-index" />.

In the left-hand navigation area, there is an Artifact Search text field next to a magnifying glass. To search for an artifact by groupId or artifactId, type in some text and click the magnifying glass. Typing in the search term "guice" and clicking the magnifying glass should yield a search result similar to <xref linkend="fig-nexus-search" />.

Once you’ve located the artifact you were looking for you can click on the pom link to download the POM or the artifact link to download the artifact.

In addition to searching by a groupId or an artifactId, Nexus has a feature which allows you to search for an artifact by a checksum.

When your build makes use of proprietary or custom dependencies which are not available from public repositories, you will often need to find a way to make them available to developers in a custom Maven repository. Nexus ships with a preconfigured 3rd Party repository that was designed to hold 3rd Party dependencies which are used in your builds. To upload artifacts to a repository, select a hosted repository in the Repositories panel and then click on the Artifact Upload tab. Clicking on the Artifact Upload tab will display the tab shown in <xref linkend="fig-using-artifact-upload" />.

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters. If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it. If you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Artifact Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times.

Nexus provides feeds that capture system events, you can browse these feeds by clicking on System Feeds under the View menu. Clicking on System Feeds will show the panel in <xref linkend="fig-repoman-system-feeds" />. You can use these simple interface to browse the most recent reports of artifact deployments, cached artifacts, broken artifacts, and storage changes that have occurred in Nexus.

These feeds can come in handy if you are working at a large organization with multiple development teams deploying to the same instance of Nexus. If such an arrangement, all developers in an organization can subscribe to the RSS feeds for New Deployed Artifacts as a way to ensure that everyone is aware when a new release has been pushed to Nexus. Exposing these system events as RSS feeds also opens to the door to other, more creative uses of this information, such as connecting Nexus to external automated testing systems. To access the RSS feeds for a specific feed, select the feed in the System Feeds view panel and then click on the Subscribe button. Nexus will then load the RSS feed in your browse and you can subscribe to the feed in your favorite RSS

There are six system feeds available in the System Feeds view, and each has a URL which resembles the following URL

Where recentChanges would be replaced with the identifier of the feed you were attempting to read. Available system feeds include:

The Logs and Config Files link is only visible to Administrative users under the Views menu. Click on this option brings up the dialog shown in <xref linkend="fig-nexus-logs" />. From this screen you can view the following log and configuration files by clicking on the drop down selection next to the Download button.

If you are running Nexus Professional, you should see a few more configuration files in this directory which will correspond to the Procurement and Staging suites. The configuration files specific to Nexus Professional are:

In <xref linkend="fig-nexus-logs" /> there is a "tail" checkbox. If this box is checked, then Nexus will always show you the end of a log file. This can come in handy if you want to see a continuously updated log file. When this tail box is checked, a dropdown at the bottom of the panel allows you to set the update frequency. The contents of this dropdown are shown in <xref linkend="fig-using-update-freq" />. If an update interval is selected, Nexus will periodically refresh the selected log file.

If you have the appropriate security privilege, you will see an option to change your password in the left-hand side of the browser. To change your password, click on change password, supply your current password, and choose a new password. When you click on Change Password, your Nexus password will be changed.

If you encounter a problem with Nexus, you can use the Nexus UI to report a bug or file an issue against the Nexus project in Sonatype’s JIRA instance. To file a problem report, you will first need to sign up for an account on http://issues.sonatype.org. In Nexus 1.6, you can click on "File Issue" in the Nexus menu, supply your Sonatype JIRA credentials, and file a problem report. Supply your JIRA username and password along with a short title and a description as shown in the following figure. When you file a Nexus problem report, Nexus will create a new issue in JIRA and attach your configuration and logs to the newly filed issue.

Many of the configuration screens shown in this section are only available to administrative users. Nexus allows the admin user to customize the list of repositories, create repository groups, customize server settings, and create routes or "rules" that Maven will use to include or exclude artifacts from a repository.

In a production installation of Nexus, you’ll probably want to customize the administrative password to something other than "admin123", and you might want to override the default directories that Nexus uses to store repository data. To do this, log in as the administrative user and click on Server under Configuration in the left-hand navigation menu. The server configuration screen is shown in <xref linkend="fig-nexus-server-config" /> and <xref linkend="fig-nexus-server-config-2" />.

This screen allows you to change:

The anonymous username and password is used to integrate with other realms that may need a special username for anonymous access. In other words, the username and password here is what we attempt to authorize when someone makes an anonymous request. You would change the anonymous username to “guest” if you wanted to integrate Nexus with Microsoft’s Active Directory.

Nexus can be configured to automatically file exception and error reports with the Nexus project in the Sonatype issue tracker. Activating this setting in your own Nexus installation helps to improve Nexus as the development team will receive automatic error reports if your Nexus instance experiences an error or a failure. The Nexus Server configuration’s Automated Error Reporting Settings section is shown in <xref linkend="fig-configuring-automated-error" />. This section accepts a JIRA username and password, and allows you to configure Nexus to use the default HTTP Proxy Settings when Nexus attempts to file an error report with the Sonatype issue tracker.

To sign up for an account on the Sonatype JIRA instance, go to http://issues.sonatype.org. Once you see the website shown in <xref linkend="fig-configuring-sonatype-jira" />, click on the "Signup" link below the Login form.

Fill out the signup form shown in <xref linkend="fig-configuring-sonatype-jira-signup" />, and choose a username and password. This is the username and password you should use in the Automated Error Reporting Settings section of the Server configuration shown in <xref linkend="fig-configuring-automated-error" />.

Nexus can notify you of new versions of Nexus via the Nexus interface. To enable this feature, check the Enable checkbox in the New Version Notification section of the Nexus server settings as shown in <xref linkend="fig-configuring-new-version" />.

To manage Nexus repositories, log in as the administrative user and click on Repositories in the Views/Repositories menu in the left-hand navigation menu. If you are logged into Nexus as a user with administrative privileges, you will see Configuration and Mirrors tabs in the lower portion of the Nexus window.

Nexus provides for three different kinds of repositories:

<xref linkend="fig-repo-config" /> shows the Repository configuration screen for a Proxy repository in Nexus. From this screen, you can manage the settings for proxying an external repository. From this screen, you can configure:

If enabled, Nexus will download the index and use that for its searches as well as serve that up to any clients which ask for the index (like m2eclipse). The default for new proxy repositories is enabled, but all of the default repositories included in Nexus have this option disabled. To change this setting for one of the proxy repositories that ship with Nexus, change the option, save the repository, and then re-index the repository. Once this is done, artifact search will return every artifact available on the Maven Central repository.

Groups are a powerful feature of Nexus, they allow you to combine multiple repositories and other repository groups in a single URL. Nexus ships with two groups: public and public-snapshots. The public group combines the three hosted repositories: 3rd Party, Releases, and Snapshots with the Maven Central repository. The public-snapshots repository combines the Apache Snapshots and Codehaus Snapshots repositories.

In <xref linkend="maven-sect-single-group" /> we configured Maven via the <filename>settings.xml to look for artifacts in the public group managed by Nexus. <xref linkend="fig-group-config" /> shows the group configuration screen in Nexus, in this figure you can see the contents of the public

Note that the order of the repositories listed in Order Group Repositories is important. When Nexus searches for an artifact in a group it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the Ordered Group Repositories selection list.

The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved by Maven from a Nexus Repository Group. We recommend placing release repositories higher in the list than snapshot repositories so that LATEST and RELEASE versions are merged appropriately. We also recommend placing repositories with a higher probability of matching the majority of artifacts higher in this list. If most of your artifacts are going to be retrieved from the Maven Central Repository, putting Central higher in this list than a smaller, more focused repository is going to be better for performance as Nexus is not going to interrogate the smaller remote repository for as many missing artifacts.

Nexus Routes are like filters you can apply to Nexus Groups, they allow you to configure Nexus to include or exclude repositories from a particular artifact search when Nexus is trying to locate an artifact in a Nexus Group. There are a number of different scenarios in which you might configure a route in Nexus, the most common is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want to make sure that you are trying to retrieve your own organization’s artifacts from the hosted Release and Snapshot repositories. Nexus Routes are applicable when you are trying to resolve an artifact from a Nexus Group; using Routes allow you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.

<xref linkend="fig-route-config" /> shows the Route Configuration screen. Clicking on a route will bring up a screen which will allow you to configure the properties of a route. The configuration options available for a route are:

In this figure you can see the two dummy Routes that Nexus has as default routes.

The first route is an inclusive route, it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public Maven repositories like the Maven Central Repository or the Apache Snapshots repository.

The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains "/org/some-oss". This example might make more sense if we replaced "some-oss" with "apache" or "codehaus". If the pattern was "/org/apache", this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.

What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that Nexus Routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a Nexus Group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the Group and the repositories in the inclusive Nexus Route. The order as defined in the Nexus Group will not be affected by the Inclusive routes. Nexus will then take the result of applying the inclusive routes and apply the exclusive routes to this new group. The resulting list is then searched for a matching artifact. One straightforward use of routes is to create a route that excludes the

Maven Central repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding Central from searches for your own artifacts will reduce needless queries to the public repositories.

To summarize, there are creative possibilities with Routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping Routes. Use Routes sparingly, and use course URL patterns, as Nexus evolves there will be more features which allow for more fine grained rules to allow you to prohibit requests for specific artifacts and specific versions of artifacts. Remember that routes are only applied to Nexus Groups, routes are not used when an artifact is requested from a specific repository.

Nexus allows you to schedule tasks that will be applied to all repositories or to specific repositories on a configurable schedule. You can create the following kinds of scheduled tasks:

Minimum Snapshots to preserve in a repository - This configuration option allows you to specify a minimum number of SNAPSHOTs to preserve per artifact. For example, if you configured this option with a value of 2, Nexus will always preserve at least two SNAPSHOT artifacts.

Snapshot Retention (in days) - This configuration option allows you to specify the number of days to retain SNAPSHOT artifacts. For example, if you want to make sure that you are always keeping the last three day’s worth of SNAPSHOT artifacts, configure this option with a value of 3.

Whether snapshots should be removed if an artifact has been released - If your Nexus repository also contains a release repository, you can configure Nexus to remove all SNAPSHOT artifacts once an artifact has been released.

When you create a new service you can configure it to apply to all repositories, the repositories in a Nexus Group, or a specific Nexus Repository. A service can be scheduled to run once at a specific date and time, or periodically once every Day, Week, or Month. If none of these options suit your specific needs, you can select a recurrence of "Advanced" which will allow you to supply your own cron expression to specify when the job should execute. To create a new scheduled task, click on Scheduled Tasks under the Administration menu, and click on the Add button. This will bring up the screen shown in <xref linkend="fig-repomap-scheduled" />.

<imageobject

Nexus has role-based access control (RBAC) which gives administrators very fine-grained control over who can read from a repository (or a subset of repositories), who can administer the server, and who can deploy to repositories. The security model in Nexus is also so flexible as to allow you to specify that only certain users or roles can deploy and manage artifacts in a specific repository under a specific groupId or asset class. The default configuration of Nexus ships with four roles and four users with a standard set of permissions that will make sense for most users. As your security requirements evolve, you’ll likely need to customize security settings to create protected repositories for multiple departments, or development groups. Nexus provides a security model which can adapt to any scenario. Nexus' Role-based access control (RBAC) system is designed around the following four security concepts:

Nexus has three types of privileges: application privileges which cover actions a user can execute in Nexus, repository target privileges which govern the level of access a user has to a particular repository or repository target, and repository view privileges which control whether a user can view a repository. Behind the scenes, a privilege is related to a single REST operation and method like create, update, delete, read.

To create a new privilege, click on the Add… button in the Privileges panel and choose Repository Target privilege. Creating a privilege will load the New Repository Target Privilege form shown in <xref linkend="fig-configuring-new-privilege" />. This form takes a privilege name, a privilege description, the repository to target, and a repository target.

Once you create a new privilege, it will create four underlying privileges: create, delete, read, and update. The four privileges created by the form in <xref linkend="fig-configuring-new-privilege" /> are shown in <xref linkend="fig-configuring-new-privileges" />.

A target is a set of regular expressions to match on a path (exactly how the route rules work now). This allows you to define for example a target called Apache Maven which is "org/apache/maven/.*" You can then add a new privilege that relates to the target and controls the CRUD operations for artifacts matching that path (the privilege can span multiple repositories if you want). You could thus delegate all control of org.apache.maven targets to a "Maven" team. In this way, you don’t need to create separate repositories for each logical division of your artifacts.

Nexus ships with four roles: Nexus Administrator Role, Nexus Anonymous Role, Nexus Developer Role, and Nexus Deployment Role. Click on the Roles link under Security in the Nexus menu to show the list of roles shown in <xref linkend="fig-configuring-security-roles" />.

To create a new role, click on the Add… button and fill out the New Nexus Role form shown in <xref linkend="fig-configuring-creating-new-role" />. When creating a new role, you will need to supply a role identifier, a role name, a description, and a session timeout. Roles are comprised of other roles and individual privileges, to assign a role or privilege to a role, click on the role or privilege under Available Roles/Privileges and drag the role or privilege to the Selected Roles/Privileges list.

The built-in roles Nexus Administrator Role, Nexus Anonymous Role, Nexus Deployment Role, and Nexus Developer Role are managed by Nexus and cannot be edited or deleted. Selecting one of these built-in roles will load the form shown in <xref linkend="fig-configuring-builtin-role" />.

A Nexus role is comprised of other Nexus roles and individual Nexus privileges. To view the component parts of a Nexus Role, select the role in the Roles panel and then choose the Role Tree tab as shown in <xref linkend="fig-configuring-role-tree" />.

With the Repository Targets, you have fine grained control over every action in the system. For example you could make a target that includes everything except sources (.(?!-sources)\.) and assign that to one group while giving yet another group access to everything. This means you can host your public and private artifacts in a single repository without giving up control of your private artifacts.

Nexus ships with three users: admin, anonymous, and deployment. The admin user has all privileges, the anonymous user has read-only privileges, and the deployment user can both read and deploy to repositories. If you need to create users with a more focused set of permissions, you can click on Users under Security in the left-hand navigation menu. Once you see the list of users, you can click on a user to edit that specific user’s user ID, name, email, or status. You can also assign or revoke specific roles or permissions for a particular user.

A user can be assigned one or more roles which in turn can include references to other Nexus roles or to individual Nexus privileges. To view a tree of assigned Nexus roles and privileges, select the Role Tree for a particular user as shown in <xref linkend="fig-configuring-security-user-role-tree" />.

If you need to find out exactly how a particular user has been granted a particular privilege, you can use the Privilege Trace pane as shown in <xref linkend="fig-configuring-security-user-priv-trace" />. The Privilege Trace pane lists all of the privileges that have been granted to a particular user. Clicking on a privilege loads a tree of roles that grant that particular privilege to a user. If a user has been assigned a specific privilege by more than one Role or Privilege assignment, you will be able to see this reflected in the Role Containment list.

By default, Nexus listens on port 8081. You can change this port, by changing the value in shown in <xref linkend="ex-plexus-props" />. To change the port, stop Nexus, change the value of applicationPort in this file, and then restart Nexus. Once you do this, you should see a log you that Nexus is listening on the altered port.

You can configure the format and level of logging from within the Nexus interface. To do this, click on Log Configuration under the Administration menu in the left-hand navigation menu. Clicking on this link will display the panel shown in <xref linkend="fig-configuring-log-config" />.

From this panel you can configure the following logging configuration properties:

The other configuration parameters: Root Logger Appenders and File Append Location, are not editable in this release of Sonatype Nexus.

Use the Nexus Plugin Console to list all installed Nexus plugins and browse REST services made available by installed Nexus Plugin. To open the Nexus Plugin Console, click on the Plugin Console link in the Administration section of the Nexus menu as shown in <xref linkend="fig-configuring_plugin-console-admin-menu" />.

Once you open the Nexus Plugin Console, you will see a list of plugins installed in your Nexus installation. Clicking on a Nexus plugin in this list will display information about the plugin including: the plugin’s name, the plugin version, status, a description, SCM information about the plugin, and the URL of the plugin’s project web site.

Once you have selected a plugin from the list of installed plugin, you can browse the available REST interfaces by selecting the REST Services tab as shown in <xref linkend="fig-configuring_plugin-console-rest" />. Each plugin can contribute one or more REST services to Nexus.